<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- qdoc-manual-markupcmds.qdoc -->
  <title>Creating Links | QDoc Manual 5.14.2</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="../qtdoc/index.html">Qt 5.14</a></td><td ><a href="qdoc-index.html">QDoc Manual</a></td><td >Creating Links</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qdoc-index.html">Qt 5.14.2 Reference Documentation</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
  <link rel="prev" href="07-0-qdoc-commands-includingexternalcode.html" />
  <link rel="next" href="09-qdoc-commands-includingimages.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="07-0-qdoc-commands-includingexternalcode.html">Including External Code</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="09-qdoc-commands-includingimages.html">Including Images</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#l-link">\l (link)</a></li>
<li class="level2"><a href="#fixing-ambiguous-links">Fixing Ambiguous Links</a></li>
<li class="level2"><a href="#what-arguments-can-appear-in-square-brackets">What arguments can appear in square brackets?</a></li>
<li class="level1"><a href="#sa-see-also">\sa (see also)</a></li>
<li class="level1"><a href="#target">\target</a></li>
<li class="level1"><a href="#keyword">\keyword</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Creating Links</h1>
<span class="subtitle"></span>
<!-- $$$08-qdoc-commands-creatinglinks.html-description -->
<div class="descr"> <a name="details"></a>
<p>These commands are for creating hyperlinks to classes, functions, examples, and other targets.</p>
<a name="l-command"></a><a name="l-link"></a>
<h2 id="l-link">\l (link)</h2>
<p>The \l link command is used to create a hyperlink to many different kinds of targets. The command's general syntax is:</p>
<pre class="cpp">

  \l <span class="operator">[</span> link criteria <span class="operator">]</span> { link target } { link text }

</pre>
<p>...where the <code>link criteria</code> in square brackets are optional but may be required when the <code>link target</code> is ambiguous. See <a href="08-qdoc-commands-creatinglinks.html#fixing-ambiguous-links">Fixing Ambiguous Links</a> below.</p>
<p>Here is an example using the \l command to link to an external page:</p>
<pre class="cpp">

  <span class="operator">/</span> <span class="operator">*</span><span class="operator">!</span>
     Read the \l {http:<span class="comment">//doc.qt.io/qt-5/}</span>
     {<span class="type"><a href="../qtcore/qt.html">Qt</a></span> <span class="number">5.0</span> Documentation} carefully<span class="operator">.</span>
  <span class="operator">*</span> <span class="operator">/</span>

</pre>
<p>QDoc renders this as:</p>
<blockquote><p>Read the <a href="http://doc.qt.io/qt-5/">Qt 5.0 Documentation</a> carefully.</p>
</blockquote>
<p>If the link target is equivalent to the link text, the second argument can be omitted.</p>
<p>For example, if you have documentation like:</p>
<pre class="cpp">

  <span class="operator">/</span> <span class="operator">*</span><span class="operator">!</span>
     \target assertions

     Assertions make some statement about the text at the
     point where they occur in the regexp<span class="operator">,</span> but they <span class="keyword">do</span> <span class="keyword">not</span>
     match any characters<span class="operator">.</span>

     <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>

     Regexps are built up from expressions<span class="operator">,</span> quantifiers<span class="operator">,</span> and
     \l {assertions} {assertions}<span class="operator">.</span>
  <span class="operator">*</span> <span class="operator">/</span>

</pre>
<p>You can simplify this as follows:</p>
<pre class="cpp">

  <span class="operator">/</span> <span class="operator">*</span><span class="operator">!</span>
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp<span class="operator">,</span> but they <span class="keyword">do</span> <span class="keyword">not</span>
    match any characters<span class="operator">.</span>

    <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>

    Regexps are built up from expressions<span class="operator">,</span> quantifiers<span class="operator">,</span> and
    \l assertions<span class="operator">.</span>
  <span class="operator">*</span> <span class="operator">/</span>

</pre>
<p>For the one-parameter version, the braces can often be omitted. The \l command supports several ways of linking:</p>
<ul>
<li><code>\l QWidget</code> - The name of a class documented with the <a href="13-qdoc-commands-topics.html#class-command">\class</a> command.</li>
<li><code>\l QWidget::sizeHint()</code> - The signature of a function without parameters. If a matching function without parameters can't be found, the link is satisfied with the first matching function found.</li>
<li><code>\l QWidget::removeAction(QAction* action)</code> - The signature of a function with parameters. If an exact match is not found, the link is not satisfied and qdoc reports a <i>Can't link to..&#x2e;</i> error.</li>
<li><code>\l &lt;QtGlobal&gt;</code> - The subject of a <a href="13-qdoc-commands-topics.html#headerfile-command">\headerfile</a> command.</li>
<li><code>\l widgets/wiggly</code> - The relative path used in an <a href="13-qdoc-commands-topics.html#example-command">\example</a> command.</li>
<li><code>\l {QWidget Class Reference}</code> - The title used in a <a href="20-qdoc-commands-namingthings.html#title-command">\title</a> command.</li>
<li><code>\l {Introduction to QDoc}</code>- The text from one of the <a href="05-qdoc-commands-documentstructure.html#section-commands">Section commands</a>.</li>
<li><code>\l fontmatching</code> - The argument of a <a href="08-qdoc-commands-creatinglinks.html#target-command">\target</a> command.</li>
<li><code>\l {Shared Classes}</code> - A keyword named in a <a href="08-qdoc-commands-creatinglinks.html#keyword-command">\keyword</a> command.</li>
<li><code>\l http://qt-project.org/</code> - A URL.</li>
</ul>
<p>QDoc also tries to make a link out of any word that doesn't resemble a normal English word, for example, Qt class names or functions, like <a href="../qtwidgets/qwidget.html">QWidget</a> or <a href="../qtwidgets/qwidget.html#sizeHint-prop">QWidget::sizeHint</a>(). In these cases, the \l command can actually be omitted, but by using the command, you ensure that QDoc will emit a warning if it cannot find the link target. In addition, if you only want the function name to appear in the link, you can use the following syntax:</p>
<ul>
<li><code>\l {QWidget::} {sizeHint()}</code></li>
</ul>
<p>QDoc renders this as:</p>
<blockquote><p><a href="../qtwidgets/qwidget.html#sizeHint-prop">sizeHint()</a></p>
</blockquote>
<a name="fixing-ambiguous-links"></a>
<h3 id="fixing-ambiguous-links">Fixing Ambiguous Links</h3>
<p>Because of the modularization of Qt beginning with Qt 5.0, The possibility that qdoc will have to deal with ambiguous links has increased. An ambiguous link is one that has a matching target in more than one Qt module, e.g&#x2e; the same section title can appear in more than one Qt module, or the name of a C++ class in one module can also be the name of a QML type in another module. A real example in Qt5 is the name Qt itself. Qt is the name of both a C++ namespace in <a href="../qtcore/qtcore-module.html">QtCore</a> and a QML type in <a href="../qtqml/qtqml.html">QtQml</a>.</p>
<p>Suppose we want to link to the <a href="../qtcore/qt.html">Qt C++ namespace</a>. At the time qdoc generated this HTML page, that link was correct. Does it still go to the C++ namespace? Qdoc generated that link from this link command:</p>
<ul>
<li><code>\l {Qt} {Qt C++ namespace}</code></li>
</ul>
<p>Now suppose we want to link to the <a href="../qtqml/qml-qtqml-qt.html">Qt QML type</a>. At the time qdoc generated this HTML page, that link was also correct, but we had to use this link command:</p>
<ul>
<li><code>\l [QML] {Qt} {Qt QML type}</code></li>
</ul>
<p>The <i>QML</i> in <i>square brackets</i> tells qdoc to accept a matching target only if the traget is on a QML page. Qdoc actually finds the C++ namespace target first, but since that target is on a C++ page, qdoc ignores it and keeps looking until it finds the same target on a QML page.</p>
<p>Without the guidance in the <i>\l command</i> in the optional <i>square bracket</i> argument, qdoc links to the first matching target it finds. qdoc can't warn that the link was ambiguous in such cases because it doesn't know that another matching target exists.</p>
<a name="what-arguments-can-appear-in-square-brackets"></a>
<h3 id="what-arguments-can-appear-in-square-brackets">What arguments can appear in square brackets?</h3>
<p>A link command with square bracket argument has the following syntax:</p>
<p><code>\l [QML|CPP|DOC|QtModuleName] {link target} {link text}</code></p>
<p>The <i>square bracket</i> argument is only allowed in the <code>\l (link)</code> command. The example above shows how <code>QML</code> is used as the <i>square brackets</i> argument to force qdoc to match a QML target. Most often, this will be a QML type, but it can also be a QML member function of property.</p>
<p>In the example, qdoc didn't need a <i>square bracket</i> argument to find the Qt C++ namespace page, because that one was the first matching target qdoc found anyway. However, to force qdoc to find a C++ target when a matching QML target gets in the way, <code>CPP</code> can be used as the <i>square bracket</i> argument. For example:</p>
<ul>
<li><code>\l [CPP] {Qt} {Qt C++ namespace}</code></li>
</ul>
<p>...will force qdoc to ignore the Qt QML type and continue searching until it matches the Qt C++ namespace.</p>
<p>If the link target is neither a C++ nor a QML entity, <code>DOC</code> can be used as the <i>square bracket</i> argument to prevent qdoc from matching either of those. At this writing, there were no cases of ambiguous links where using <code>DOC</code> was required.</p>
<p>Often, the documentor knows which Qt module the link target is in. When the module name is known, use the module name as the <i>square bracket</i> argument. In the example above, if we know that the QML type named Qt is located in the <a href="../qtqml/qtqml.html">QtQml</a> module, we can write the link command like this:</p>
<ul>
<li><code>\l [QtQml] {Qt} {Qt QML type}</code></li>
</ul>
<p>When a module name is used as the <i>square bracket</i> argument, qdoc will search for link the target in that module only. This makes searching for link targets more efficient.</p>
<p>Finally, the module name and entity type arguments can be combined, separated by a blank, so something like this is also allowed:</p>
<ul>
<li><code>\l [CPP QtQml] {Window} {C++ class Window}</code></li>
</ul>
<p>As of this writing, there were no cases where combining the two was required.</p>
<p>See also <a href="08-qdoc-commands-creatinglinks.html#sa-command">\sa</a>, <a href="08-qdoc-commands-creatinglinks.html#target-command">\target</a>, and <a href="08-qdoc-commands-creatinglinks.html#keyword-command">\keyword</a>.</p>
<a name="sa-command"></a><a name="sa-see-also"></a>
<h2 id="sa-see-also">\sa (see also)</h2>
<p>The \sa command defines a list of links that will be rendered in a separate &quot;See also&quot; section at the bottom of the documentation unit.</p>
<p>The command takes a comma-separated list of links as its argument. If the line ends with a comma, you can continue the list on the next line. The general syntax is:</p>
<pre class="cpp">

  \sa {the first link}<span class="operator">,</span> {the second link}<span class="operator">,</span>
      {the third link}<span class="operator">,</span> <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>

</pre>
<p>QDoc will automatically try to generate &quot;See also&quot; links interconnecting a property's various functions. For example, a setVisible() function will automatically get a link to visible() and vice versa.</p>
<p>In general, QDoc will generate &quot;See also&quot; links that interconnect the functions that access the same property. It recognizes four different syntax versions:</p>
<ul>
<li><code>property()</code></li>
<li><code>setProperty()</code></li>
<li><code>isProperty()</code></li>
<li><code>hasProperty()</code></li>
</ul>
<p>The \sa command supports the same kind of links as the <a href="08-qdoc-commands-creatinglinks.html#l-command">\l</a> command.</p>
<pre class="cpp">

  <span class="operator">/</span> <span class="operator">*</span><span class="operator">!</span>
     Appends the actions \a actions to <span class="keyword">this</span> widget<span class="char">'s
     list of actions.

     \sa removeAction(), QMenu, addAction()
  * /
  void QWidget::addActions(QList&lt;QAction *&gt; actions)
  {
  ...
  }
  </span>

</pre>
<p>QDoc renders this as:</p>
<blockquote><p><b>void <a href="../qtwidgets/qwidget.html#addActions">QWidget::addActions</a> ( <a href="../qtcore/qlist.html">QList</a>&lt;<a href="../qtwidgets/qaction.html">QAction</a>*&gt; <i>actions</i> )</b></p>
<p>Appends the actions <i>actions</i> to this widget's list of actions.</p>
<p>See also <a href="../qtwidgets/qwidget.html#removeAction">removeAction()</a>, <a href="../qtwidgets/qmenu.html">QMenu</a>, and <a href="../qtwidgets/qwidget.html#addAction">addAction()</a>.</p>
</blockquote>
<p>See also <a href="08-qdoc-commands-creatinglinks.html#l-command">\l</a>, <a href="08-qdoc-commands-creatinglinks.html#target-command">\target</a> and <a href="08-qdoc-commands-creatinglinks.html#keyword-command">\keyword</a>.</p>
<a name="target-command"></a><a name="target"></a>
<h2 id="target">\target</h2>
<p>The \target command names a place in the documentation that you can link to using the <a href="08-qdoc-commands-creatinglinks.html#l-command">\l (link)</a> and <a href="08-qdoc-commands-creatinglinks.html#sa-command">\sa (see also)</a> commands.</p>
<p>The text up to the line break becomes the target name. Be sure to follow the target name with a line break. Curly brackets are not required around the target name, but they may be required when the target name is used in a link command. See below.</p>
<pre class="cpp">

  <span class="operator">/</span> <span class="operator">*</span><span class="operator">!</span>
      \target capturing parentheses
      \section1 Capturing Text

      Parentheses allow us to group elements together so that
      we can quantify and capture them<span class="operator">.</span>

      <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
  <span class="operator">*</span> <span class="operator">/</span>

</pre>
<p>The target name <i>capturing parentheses</i> can be linked from within the same document containing the target in the following way:</p>
<ul>
<li><code>\l {capturing parentheses}</code> (from within the same QDoc comment)</li>
</ul>
<p><b>Note: </b>The brackets in the link example are required because the target name contains spaces.</p><p>See also <a href="08-qdoc-commands-creatinglinks.html#l-command">\l</a>, <a href="08-qdoc-commands-creatinglinks.html#sa-command">\sa</a> and <a href="08-qdoc-commands-creatinglinks.html#keyword-command">\keyword</a>.</p>
<a name="keyword-command"></a><a name="keyword"></a>
<h2 id="keyword">\keyword</h2>
<p>The \keyword command names a place in the documentation that you can link to using the <a href="08-qdoc-commands-creatinglinks.html#l-command">\l (link)</a> and <a href="08-qdoc-commands-creatinglinks.html#sa-command">\sa (see also)</a> commands.</p>
<p>The \keyword command is like the <a href="08-qdoc-commands-creatinglinks.html#target-command">\target</a> command, except when linking to keyword the link goes to the top of the QDoc comment where the \keyword appears in. If you want to create a link target to a <code>section</code> unit within a \page, use \target instead. A keyword can be linked from anywhere using a simple syntax.</p>
<p>Keywords must be unique over all the documents processed during the QDoc run. The command uses the rest of the line as its argument. Be sure to follow the keyword with a line break.</p>
<pre class="cpp">

  <span class="operator">/</span> <span class="operator">*</span><span class="operator">!</span>
      \<span class="keyword">class</span> <span class="type"><a href="../qtcore/qregexp.html">QRegExp</a></span>
      \reentrant
      \brief The <span class="type"><a href="../qtcore/qregexp.html">QRegExp</a></span> <span class="keyword">class</span> provides pattern
             matching <span class="keyword">using</span> regular expressions<span class="operator">.</span>
      \ingroup tools
      \ingroup misc
      \ingroup shared

      \keyword regular expression

      Regular expressions<span class="operator">,</span> <span class="keyword">or</span> <span class="string">&quot;regexps&quot;</span><span class="operator">,</span> provide a way to
      find patterns within text<span class="operator">.</span>

      <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
  <span class="operator">*</span> <span class="operator">/</span>

</pre>
<p>The location marked with the keyword can be linked to with:</p>
<pre class="cpp">

  <span class="operator">/</span> <span class="operator">*</span><span class="operator">!</span>
      When a string is surrounded by slashes<span class="operator">,</span> it is
      interpreted as a \l {<span class="type"><a href="../qtcore/qregexp.html">QRegExp</a></span>}{regular expression}<span class="operator">.</span>
  <span class="operator">*</span> <span class="operator">/</span>

</pre>
<p>QDoc renders this as:</p>
<blockquote><p>When a string is surrounded by slashes, it is interpreted as a <a href="../qtcore/qregularexpression.html">regular expression</a>.</p>
</blockquote>
<p>If the keyword text contains spaces, the brackets are required.</p>
<p>See also <a href="08-qdoc-commands-creatinglinks.html#l-command">\l (link)</a>, <a href="08-qdoc-commands-creatinglinks.html#sa-command">\sa (see also)</a> and <a href="08-qdoc-commands-creatinglinks.html#target-command">\target</a>.</p>
</div>
<!-- @@@08-qdoc-commands-creatinglinks.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="07-0-qdoc-commands-includingexternalcode.html">Including External Code</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="09-qdoc-commands-includingimages.html">Including Images</a>
</p>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2020 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br/>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br/>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
